/*******************************************************************************
*
*               COPYRIGHT (c) 2015-2016 Broadlink Corporation
*                         All Rights Reserved
*
* The source code contained or described herein and all documents
* related to the source code ("Material") are owned by Broadlink
* Corporation or its licensors.  Title to the Material remains
* with Broadlink Corporation or its suppliers and licensors.
*
* The Material is protected by worldwide copyright and trade secret
* laws and treaty provisions. No part of the Material may be used,
* copied, reproduced, modified, published, uploaded, posted, transmitted,
* distributed, or disclosed in any way except in accordance with the
* applicable license agreement.
*
* No license under any patent, copyright, trade secret or other
* intellectual property right is granted to or conferred upon you by
* disclosure or delivery of the Materials, either expressly, by
* implication, inducement, estoppel, except in accordance with the
* applicable license agreement.
*
* Unless otherwise agreed by Broadlink in writing, you may not remove or
* alter this notice or any other notice embedded in Materials by Broadlink
* or Broadlink's suppliers or licensors in any way.
*
*******************************************************************************/

#ifndef __DNA_I2C_H
#define __DNA_I2C_H

#ifdef __cplusplus
    extern "C" {
#endif

/** @defgroup dna_i2c_enum Enum
  * @{
  */

/** @brief This enum define the I2C port  */
enum {
    DNA_I2C_MASTER_0 = 0,
    DNA_I2C_MASTER_1,
    DNA_I2C_MASTER_MAX                                /**< max i2c master number, <invalid> */
};

/** @brief This enum define the I2C transaction speed  */
enum {
    DNA_I2C_FREQUENCY_50K = 0,                        /**<  Transmit data with 50kbps. */ 
    DNA_I2C_FREQUENCY_100K,                           /**<  Transmit data with 100kbps. */ 
    DNA_I2C_FREQUENCY_200K,                           /**<  Transmit data with 200kbps. */ 
    DNA_I2C_FREQUENCY_400K,                           /**<  Transmit data with 400kbps. */ 
    DNA_I2C_FREQUENCY_MAX,                            /**<  Max transaction speed, don't use this value. */ 
};

/** @brief This enum define the I2C interface API error code (return value)  */
enum {
    DNA_I2C_STATUS_ERROR = -4,                        /**<  An error occurred and the transaction failed. */
    DNA_I2C_STATUS_ERROR_BUSY,	                      /**<  I2C bus busy error is given. */
    DNA_I2C_STATUS_INVALID_PORT_NUMBER,               /**<  A wrong port number is given. */ 
    DNA_I2C_STATUS_INVALID_PARAMETER,                 /**<  A wrong parameter is given. */ 
    DNA_I2C_STATUS_OK,                                /**<  No error occurred during the function call. */ 
};

/** @brief  The maximum polling mode transaction size.
  */
#define DNA_I2C_MAXIMUM_POLLING_TRANSACTION_SIZE      8

/** @brief  The maximum DMA mode transaction size.
  */
#define DNA_I2C_MAXIMUM_DMA_TRANSACTION_SIZE          255

/** @brief This enum defines the transaction result event. These results will be passed to user using a callback function. 
  *  Please refer #dna_i2c_register_callback() for more details. 
  */
enum {
    DNA_I2C_EVENT_ACK_ERROR = -3,                     /**<  An ACK error occurred during transaction. */ 
    DNA_I2C_EVENT_NACK_ERROR,                         /**<  A NACK error occurred during transaction.*/ 
    DNA_I2C_EVENT_TIMEOUT_ERROR,                      /**<  A timeout error occurred during transaction.*/ 
    DNA_I2C_EVENT_SUCCESS,                            /**<  The transaction completed wihtout any error. */ 
};

/** @brief  This defines the callback function prototype.
 *          User should register a callback function while using DMA mode.
 *          This function is called after the transaction finishes in the I2C ISR routine.
 *          For more details about the callback, please refer to #dna_i2c_register_callback().
 *  @param [in] slave_address is a user defined slave address to send or receive data.
 *  @param [in] event is the transaction event of current transaction. This parameter can tell user the transaction result. 
 *  @param [in] user_data is the user defined parameter obtained from #dna_i2c_register_callback() function.
 */
typedef void (* dna_i2c_callback_t)(unsigned char slave_address, int event, void * user_data);


/**
  * @}
  */
  

/**
 * @brief Initialize the I2C master before starting a transaction.
 * @param[in] port is the I2C master port number.
 * @param[in] speed is the I2C master transaction speed.
 * @return #DNA_I2C_STATUS_INVALID_PORT_NUMBER means an invalid port number is given; \n
 *         #DNA_I2C_STATUS_INVALID_PARAMETER means an invalid transfer_frequency is given; \n
 *         #DNA_I2C_STATUS_OK means this function completed successfully.
 *         #DNA_I2C_STATUS_ERROR_BUSY means the I2C bus is in use.
 * @note   #dna_i2c_deinit() must be called when I2C is no longer in use, or the I2C resource will not be released and other users cannot
 *         use this I2C master.
 * @waring
 */
int dna_i2c_init(int port, int speed);

/**
 * @brief Release the I2C master after the transaction is over. User must call this function if I2C is no longer in use.
 * @param[in] port is the I2C master port number.
 * @return  #DNA_I2C_STATUS_INVALID_PORT_NUMBER means an invalid port number is given; \n
 *          #DNA_I2C_STATUS_OK means this function completed successfully.
 * @note   This function must be called when I2C is no longer in use, or the I2C resource will not be released and other users can
 *         not use this I2C master.
 * @waring
 */
int dna_i2c_deinit(int port);

/**
 * @brief Send data to slave with polling mode.
 *  This function will not return until the transaction finishes.
 * @param[in] port is the I2C master port number.
 * @param[in] slave_address is the I2C slave address.
 * @param[in] data is the data buffer to send.
 * @param[in] size is the data size to send. The maximum value is #DNA_I2C_MAXIMUM_POLLING_TRANSACTION_SIZE.
 * @return   #DNA_I2C_STATUS_INVALID_PORT_NUMBER means an invalid port number is given; \n
 *           #DNA_I2C_STATUS_INVALID_PARAMETER means a NULL buffer pointer is given by user; \n
 *           #DNA_I2C_STATUS_OK means this function completed successfully; \n
 *           #DNA_I2C_STATUS_ERROR means a hardware error occurred during the transaction.\n
 *           #DNA_I2C_STATUS_ERROR_BUSY means the I2C bus is in use.
 * @note
 * @waring
 */
int dna_i2c_write(int port, unsigned char slave_address, const unsigned char * data, unsigned int size);

/**
 * @brief Send data to slave with DMA mode.
 *  This function returns a value immediately after finishing setting the hardware register.
 * @param[in] port is the I2C master port number.
 * @param[in] slave_address is the I2C slave address.
 * @param[in] data is the data buffer to send.
 * @param[in] size is the data size to send. The maximum value is #DNA_I2C_MAXIMUM_DMA_TRANSACTION_SIZE.
 * @return   #DNA_I2C_STATUS_INVALID_PORT_NUMBER means an invalid port number is given; \n
 *           #DNA_I2C_STATUS_INVALID_PARAMETER means an NULL buffer pointer is given by user; \n
 *           #DNA_I2C_STATUS_OK means this function completed successfully; \n
 *           #DNA_I2C_STATUS_ERROR_BUSY means the I2C bus is in use.
 * @note
 * @waring
 */
int dna_i2c_dma_write(int port, unsigned char slave_address, const unsigned char * data, unsigned int size);

/**
 * @brief Receive data from slave in a polling mode.
 * @param[in] port is the I2C master port number.
 * @param[in] slave_address is the I2C slave address.
 * @param[out] buffer is the data buffer to receive.
 * @param[in] size is the data size to receive. The maximum value is #DNA_I2C_MAXIMUM_POLLING_TRANSACTION_SIZE.
 * @return   #DNA_I2C_STATUS_INVALID_PORT_NUMBER means an invalid port number is given; \n
 *           #DNA_I2C_STATUS_INVALID_PARAMETER means a NULL buffer pointer is given by user; \n
 *           #DNA_I2C_STATUS_OK means this function completed successfully; \n
 *           #DNA_I2C_STATUS_ERROR means a hardware error occurred during the transaction. \n
 *           #DNA_I2C_STATUS_ERROR_BUSY means the I2C bus is in use.
 * @note
 * @waring
 */
int dna_i2c_read(int port, unsigned char slave_address, unsigned char * buffer, unsigned int size);

/**
 * @brief Receive data from slave in a DMA mode.
 *  This function will return a value immediately after finishing setting the hardware register. 
 * @param[in] port is the I2C master port number.
 * @param[in] slave_address is the I2C slave address.
 * @param[out] buffer is the data buffer to receive. 
 * @param[in] size is the data size to receive. The maximum value is #DNA_I2C_MAXIMUM_DMA_TRANSACTION_SIZE.
 * @return   #DNA_I2C_STATUS_INVALID_PORT_NUMBER means an invalid port number is given; \n
 *           #DNA_I2C_STATUS_INVALID_PARAMETER means a NULL buffer pointer is given by user; \n
 *           #DNA_I2C_STATUS_OK means this function completed successfully; \n
 *           #DNA_I2C_STATUS_ERROR_BUSY means the I2C bus is in use.
 * @note
 * @waring
 */
int dna_i2c_dma_read(int port, unsigned char slave_address, unsigned char * buffer, unsigned int size);

/**
 * @brief Register the callback function while using DMA mode.
 *        The callback function will be called at I2C ISR routine after the I2C triggers an interrupt.
 *        Always call this function to register a callback function while using DMA mode.
 * @param[in] port is the I2C master port number.
 * @param[in] i2c_callback is the callback function given by user, which will be called at I2C ISR routine.
 * @param[in] user_data is a parameter given by user and will pass to user while the callback function is called.
 * @return   #DNA_I2C_STATUS_INVALID_PORT_NUMBER means an invalid port number is given; \n
 *           #DNA_I2C_STATUS_INVALID_PARAMETER means a NULL function pointer is given by user; \n
 *           #DNA_I2C_STATUS_OK means this function completed successfully.
 * @note
 * @waring
 */
int dna_i2c_register_callback(int port, dna_i2c_callback_t i2c_callback, void * user_data);

#ifdef __cplusplus
}
#endif

#endif
